home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr39 / bpq406f.zip / BPQHOST.DOC < prev    next >
Text File  |  1992-09-06  |  10KB  |  386 lines
  1.             G8BPQ Host Mode
  2.  
  3. From Version 4.00, a new application interface to the switch is provided.
  4. This replaces the existing interfaces (TNC2, PK Host and KISS). New
  5. software should if possible use the new interface - interface routines
  6. supporting the old modes, and WA8DED Host mode, will be provided as TSRs
  7. to support existing application software.
  8.  
  9. The interface is normally called using INT 7Fh. From version 4.03 the interrupt
  10. number may be changed - The value is specified in BPQCFG.TXT as INTERRUPT=nnn,
  11. where nnn is in decimal. The function required is in AH, and the stream in AL.
  12. The system supports 64 streams, or sessions, numbered from 1 - 64.
  13.  
  14. Changes in Version 4.05.
  15.  
  16. 1.    Additional option on funtion 6 - allows connects using BBS Call, even
  17.     if APPLMASK is not set (say to prevent connects).
  18.  
  19. 2.    Additional info returned by function 8.
  20.  
  21. 3.    Format of frame returned by function 11 added to documentation.
  22.  
  23. 4.    Function 15 added. Simplifies access to timing info.
  24.  
  25. 5.     Broadcast option added. If function 2 is called with AL=0, the
  26.     data will be sent as a UI frame to all ports which have an UNPROTO
  27.     address set.
  28.  
  29. 6.     Function 12 added to update Beacon text. 
  30.  
  31.  
  32. Commands supported are:
  33.  
  34. Note that in all cases where a string is returned, ES:DI must point to
  35. a buffer supplied by the user, and the switch will copy the data to 
  36. this buffer. The code does NOT return pointers to its own data.
  37.  
  38.  
  39.     AH = 1    Set application mask to value in DL.
  40.         Set application flags to value in CL.
  41.           If top bit of CL is set, monitored frames will be available.
  42.           Use function 11 to receive them. 
  43.  
  44.     AH = 2    Send frame in ES:SI (length CX)
  45.  
  46.  
  47.     AH = 3    Receive frame into buffer at ES:DI, length of frame returned
  48.         in CX.  BX returns the number of outstanding frames still to
  49.         be received (ie. after this one) or zero if no more frames
  50.         (ie. this is last one).
  51.         Note that CX is NOT an input param - the supplied buffer
  52.         must be big enough to receive a full AX.25 frame, including
  53.         up to 8 digi callsigns. 340 should be enough.
  54.  
  55.  
  56.     AH = 4    Get stream status.  Returns:
  57.  
  58.         CX = 0 if stream disconnected or CX = 1 if stream connected
  59.         DX = 0 if no change of state, or DX = 1 if
  60.                the connected/disconnected state has changed.
  61.  
  62.     AH = 5    ACK stream status change. Must be called to allow another
  63.         status change to be reported. 
  64.  
  65.  
  66.     AH = 6    Session control.
  67.  
  68.         CX = 0 Connect to Node. Session uses BBS callsign if bottom
  69.                     bit of DL=1, otherwise uses Node Call .
  70.  
  71.         CX = 1 Connect to Node. Session uses BBS Call if APPLMASK=1,
  72.                     otherwise Node Call.
  73.  
  74.         CX = 2 Disconnect
  75.         CX = 3 Return user to node
  76.  
  77.  
  78.     AH = 7    Get buffer counts for stream.  Returns:
  79.  
  80.         BX = number of frames queued for receive
  81.         CX = number of un-acked frames to be sent
  82.         DX = number of buffers left in node
  83.  
  84.  
  85.     AH = 8    Port control/information.  Called with a stream number
  86.         in AL returns:
  87.  
  88.         ES:DI = CALLSIGN (10 bytes space padded)
  89.  
  90.         The following are now supported (4.05 onwards)
  91.  
  92.         AL = Radio port on which channel is connected (if level 2)
  93.         AH = Session Type (If Connected). Session type bits are:
  94.  
  95.            L2LINK    EQU    1
  96.            SESSION    EQU    10B
  97.            UPLINK    EQU    100B
  98.            DOWNLINK    EQU    1000B
  99.            BPQHOST    EQU    100000B
  100.     
  101.         BX = L2 paclen for the session
  102.         CX = Maxframe. Taken from PORT maxframe if L2 session,
  103.              Switch maxframe if L4.
  104.         DX = L4 window size (if L4 circuit, or zero)
  105.  
  106.  
  107.     AH = 10    RAW (KISS) transmit frame.  Data pointed to by ES:SI, of
  108.         length CX, is transmitted as a HDLC frame on the radio
  109.         port (not stream) in AL.
  110.  
  111.  
  112.     AH = 11 Get Trace (RAW Data) Frame into ES:DI, Length to CX. Data
  113.         is as received off air (ie with calls in AX.25 format, etc)
  114.         See note on CX under function 3.
  115.  
  116.         The returned buffer includes a 5 byte header:
  117.  
  118.             Bytes 0-1  - Internal control info (ignore)
  119.             Byte  2    - Port number. Top bit set if transmitted frame.
  120.             Bytes 3-4  - Frame length (including this header)
  121.  
  122.  
  123.     AH = 12 Update Switch Info. This will be used for a number of
  124.         operations. At the moment the only one implemented is to
  125.         update the Beacon Text field.
  126.  
  127.         DX = Function Number.
  128.         
  129.            DX = 1  Update Beacon Text.
  130.  
  131.             ES:SI Data to send in Beacons
  132.             CX    Length of Data
  133.  
  134.     AH = 15 Get time marker in AX. Value is number of timer interrupts
  135.         since switch was loaded, modulo 65536. Timer interrupts 
  136.         normally occur at approx 18.2 per second.
  137.  
  138.  
  139.  
  140.     The following additions have been proposed. Similar functions may
  141.     be provided, but not necessarily in this format.
  142.  
  143.  
  144.     AH = 0    Get node/switch version number and description.  On return
  145.         AH = major version number and AL = minor version number,
  146.         and user's buffer pointed to by ES:SI is set to the text
  147.         string normally output by the USERS command. CX is set to the
  148.         length of the text string.
  149.  
  150.  
  151.     AH = 9    Fetch node/application callsign & alias or application names
  152.  
  153.         AL = application
  154.         BL = 0 to get Callsign, 1 to get Application Name
  155.  
  156.         number:
  157.  
  158.         0 = node
  159.         1 = BBS
  160.         2 = HOST
  161.         3 = SYSOP etc. etc.
  162.  
  163.         Returns string with alias & callsign or application name in
  164.         user's buffer pointed to by ES:SI length CX.  For example:
  165.  
  166.         "WORCS:G8TIC"  or "TICPMS:G8TIC-10".
  167.  
  168.  
  169.  
  170. PACLEN.
  171.  
  172. Frames are transmitted as received from the application, so the application
  173. is responsible for the transmitted PACLEN. Function 8 will return the
  174. recommended value for the current session. I think the value is always OK,
  175. but I suggest you treat a value of zero as 'undefined', and use your own
  176. default. The value may change during a session, if for instance, you connect
  177. to the switch, and then out on a port with a different PACLEN. Also at
  178. some time in the future I hope to adjust PACLEN to suit conditions on the
  179. channel. So I recommend that the value is re-read from time to time during
  180. a session.
  181.  
  182.  
  183.  
  184. The following sample of code shows how to find the Interrupt Number to use
  185. to call the switch, and check that the switch is loaded.
  186.  
  187.  
  188. NOTBPQERROR    DB    'Switch not found$'
  189. VERSERROR    DB    'Version not compatible with Node Software$'
  190. G8BPQ        DB    'G8BPQ'
  191.  
  192.  
  193.  
  194. BADCONFIGMSG    DB    'Configuration file read error',0DH,0AH,'$'
  195. CONFIGFILENAME    DB    'BPQCFG.BIN',0
  196. NOCONFIGMSG    DB    'Configuration file BPQCFG.BIN not found',0DH,0AH,'$'
  197. ;
  198. ;    BPQCFG FIRST 128 BYTES
  199. ;
  200. CONFIGTABLE    LABEL    BYTE
  201. ;
  202. ;    CONFIGURATION DATA STRUCTURE
  203. ;
  204. ;    DEFINES LAYOUT OF CONFIG RECORD PRODUCED BY CONFIGURATION PROG
  205. ;
  206. ;    LAYOUT MUST MATCH THAT IN CONFIG.C SOURCE
  207. ;
  208. C_NODECALL    DB    10 DUP (0)     ; OFFSET = 0 
  209. C_NODEALIAS    DB    10 DUP (0)     ; OFFSET = 10
  210. C_BBSCALL    DB    10 DUP (0)     ; OFFSET = 20
  211. C_BBSALIAS    DB    10 DUP (0)     ; OFFSET = 30
  212. ;
  213. C_OBSINIT    DW    0         ; OFFSET = 40
  214. C_OBSMIN    DW    0         ; OFFSET = 42
  215. C_NODESINTERVAL    DW    0         ; OFFSET = 44
  216. C_L3TIMETOLIVE    DW    0         ; OFFSET = 46
  217. C_L4RETRIES    DW    0         ; OFFSET = 48
  218. C_L4TIMEOUT    DW    0         ; OFFSET = 50
  219. C_BUFFERS    DW    0         ; OFFSET = 52
  220. C_PACLEN    DW    0         ; OFFSET = 54
  221. C_TRANSDELAY    DW    0         ; OFFSET = 56
  222. C_T3        DW    0         ; OFFSET = 58
  223.            DW    0         ; OFFSET = 60
  224.         DW    0         ; OFFSET = 62
  225. C_IDLETIME    DW    0         ; OFFSET = 64
  226. C_EMSFLAG    DB    0         ; OFFSET = 66
  227.         DB    0
  228. C_BBS        DB    0         ; OFFSET = 68
  229. C_NODE        DB    0         ; OFFSET = 69
  230. C_HOSTINTERRUPT    DB    0         ; OFFSET = 70
  231. C_DESQVIEW    DB    0         ; OFFSET = 71
  232. C_MAXLINKS    DW    0         ; OFFSET = 72
  233. C_MAXDESTS    DW    0
  234. C_MAXNEIGHBOURS    DW    0
  235. C_MAXCIRCUITS    DW    0        ; 78
  236.  
  237. C_TNCPORTLISTO    DB    16 DUP (0)     ; OFFSET = 80
  238.  
  239. C_IDINTERVAL    DW    0        ; 96
  240. C_XXXXXXXX    DW    0        ; 98    ; SPARE (WAS DIGIFLAG)
  241. C_MINQUAL    DW    0        ; 100
  242. C_HIDENODES    DB    0        ; 102
  243. C_L4DELAY    DW    0        ; 103
  244. C_L4WINDOW    DW    0        ; 105
  245. C_BTINTERVAL    DW    0        ; 106
  246. X_UNPROTO    DB    9 DUP (0)    ; 108    ; NOW SPARE
  247. C_BBSQUAL    DW    0        ; 117
  248.         DB    (CONFIGTABLE+128-$) DUP (0)
  249.  
  250.  
  251.  
  252. CONFIGHANDLE    DW    0
  253.  
  254. NODE:
  255.  
  256.     INT    7FH
  257.     RET
  258.  
  259.  
  260. INIT:
  261. ;
  262. ;    GET NODE INTERRUPT NUMBER FROM CONFIG FILE
  263. ;
  264.     MOV    DX,OFFSET CONFIGFILENAME
  265.     MOV    AH,3DH
  266.     MOV    AL,0            ; READ ONLY
  267.     INT    21H            ; OPEN IT
  268.  
  269.     JC    NOCONFIGFILE
  270.  
  271.     MOV    CONFIGHANDLE,AX
  272.  
  273.     MOV    BX,AX
  274.     MOV    DX,OFFSET CONFIGTABLE
  275.     MOV    CX,128
  276.     MOV    AH,3FH
  277.  
  278.     INT    21H            ; READ
  279.     CMP    AX,CX
  280.     JNE    SHORTCONFIG
  281.  
  282.     JMP SHORT PROCESSCONFIG
  283.  
  284. NOCONFIGFILE:
  285.  
  286.     MOV    DX,OFFSET NOCONFIGMSG
  287.     JMP SHORT CONFIGERR
  288.  
  289. SHORTCONFIG:
  290.  
  291.     MOV    DX,OFFSET BADCONFIGMSG
  292.  
  293. CONFIGERR:
  294.  
  295.     MOV    AH,9
  296.     INT    21H
  297.  
  298.     MOV    AX,4C01H
  299.     INT    21H            ; EXIT
  300.  
  301. PROCESSCONFIG:
  302.  
  303.     MOV    BX,CONFIGHANDLE
  304.     MOV    AH,3EH
  305.     INT    21H            ; CLOSE IT
  306.  
  307.     MOV    AL,C_HOSTINTERRUPT    ; INTERRUPT
  308.     MOV    BYTE PTR NODE+1,AL    ; PATCH NODE CALL INSTRUCTION
  309. ;
  310. ;    GET NODE VERSION
  311. ;
  312.     PUSH    DS
  313.     MOV    AH,0
  314.     ADD    AX,AX            ; VECTORS ARE 4 BYTES LONG
  315.     ADD    AX,AX
  316.     MOV    SI,AX
  317.  
  318.     XOR    AX,AX
  319.     MOV    DS,AX
  320.  
  321.     LDS    SI,DS:[SI]        ; GET POINTER TO HOST SUPPORT CODE
  322.  
  323.     SUB    SI,7
  324.     MOV    DI,OFFSET G8BPQ
  325.     MOV    CX,5
  326.     REP CMPSB            ; MAKE SURE SWITCH IS LOADED
  327.  
  328.     JE    SWITCHOK
  329.  
  330.     POP    DS
  331.  
  332.     MOV    DX,OFFSET NOTBPQERROR
  333.  
  334.     MOV    AH,9
  335.     INT    21H
  336.  
  337.     JMP SHORT EXIT
  338.  
  339. SWITCHOK:
  340.  
  341.     CMP    BYTE PTR DS:[SI],MAJORVERSION
  342.     JNE    BADVERSION
  343.  
  344.     CMP    BYTE PTR DS:1[SI],MINORVERSION
  345.     JE    VERSIONOK
  346.  
  347.  
  348. BADVERSION:
  349.  
  350.     POP    DS
  351.  
  352.     MOV    DX,OFFSET VERSERROR
  353.     MOV    AH,9
  354.     INT    21H
  355.  
  356. EXIT:
  357.     MOV    AX,4C00H
  358.     INT    21H
  359.  
  360. BADPORTVAL:
  361.  
  362.     MOV    AH,9
  363.     MOV    DX,OFFSET ERRORMSG
  364.     INT    21H
  365.  
  366.     RET
  367.  
  368. VERSIONOK:
  369.  
  370.     POP    DS
  371. ;
  372.     ..........
  373.  
  374.  
  375.  
  376. The release disk also contains a demonstration terminal program, TERM4,
  377. written by G8IMB (in PASCAL) to demonstate the use of the new interface from
  378. a high level language. Note, however, that it was written for version 4.02,
  379. and therefore only works with the Host Mode interrupt configred at 7Fh
  380.  
  381.  
  382.  
  383. John Wiseman, G8BPQ @ GB7BAD
  384. 20/12/91
  385. Revised 5/9/92
  386.